getSchedule
getSchedule is called by a server client to retrieve schedule information for a specified time period. The schedule data is returned in the reply message. A minimal amount of customization is available.
The minimum amount of time you can retrieve is one hour, the maximum 24 hours. It is not possible to retrieve partial hours.
Sample Request
<mmRequest command="getSchedule" station="ID" [version="1"] [client=""] [userData=""]> <contents> <startTime>yyyy-mm-ddThh:00:00</startTime> <endTime> yyyy-mm-ddThh:00:00</endTime> [<properties> <property name="propName">value</property> </properties>] [<fields> <field id="101" /> <field name="Title" /> </fields>] </contents> </mmRequest>
Request Notes
startTime – The first hour to include in the reply. This is the first full hour that will be included.
endTime – The last hour to include in the reply. This is the last full hour that will be included. It defaults as YYYY-MM-DDTHH:59:SS.
Requests for more than 24 hours of schedule data will not be accepted. It is not currently possible to request a portion of an hour.
properties – Include one property tag for each query property you wish to specify. The following properties are currently available:
- description = Include element description in element tags (default=True)
- estimate = Include the estimated length of unscheduled positions when calculating airtime (default=False)
- songList = Include detailed song section after elements (default=True)
- mergeTraffic = Include merged spots in the returned schedule, if available (default=False)
- lockHours = Lock Format Clocks and save these hours in history, if needed (default=False)
- elementFilter = List of element types to include (default=Include All). This is a string of letter indicating the elements that you want included. Leave out any codes for the elements to ignore.
- L = LogNote
- M = Scheduled Music
- S = Stopset (This is actually any Lognote type element with the Sweep marker flag set)
- T = Traffic
- U = Unscheduled Music
- W - Show Marker
- * = Timing Checkpoint
- @ = Format List
- fields - The fields section must contain one field tag for each song field you wish to include in the reply message. You can use the id attribute with the internal field ID codes, or a name attribute with the user-specified field name. Only the specified fields will be returned for each song. However, the internal song ID number will always be included in the reply. You can obtain a list of available fields with the command. See Appendix C - Song Field Request Options for addition options that can be used with your fields specification.
Note that the fields section is optional. If not specified, only the song id, runtime and the primary and secondary fields will be returned. Typically, primary and secondary fields are defined as title and artist.
Sample Reply
<mmReply command="getSchedule" station="ID" version="1" [userData=""] status="ok"> <contents>
<schedule startTime="2022-03-11T00:00:00" endTime="2022-03-11T00:59:00">
<schedule> <element airDate="" airTime="" runTime="" class="" type="" [sweep="1"] [fill="1"] [songId="1"] properties="ER" historyId="">Description</element> </schedule> <songList> <song songId="1"> <field id="100" name="Description">Beatles / Yesterday</field> <field id="101" name="Artist">Beatles</field> </song> </songList> </contents> </mmreply>
Within the Reply, there are several sections that may be included, if applicable.
schedule
The schedule data is returned in the schedule section. Each scheduled element has an element tag. The following attributes are included for each element:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| Airdate= | Scheduled air date (yyyy-mm-dd) |
| Airtime= | Scheduled air time (hh:mm:ss) |
| Class= |
Element class code: L = Lognote S = Stopset T = Traffic (spot) * = Timing Element M = Scheduled Song U = Unscheduled Song |
| Fill= | 1 = element is a fill song |
| historyID= | historyId Unique ID for each history element |
| Properties= |
String of letter codes. L=Locked, E=No Export R=No Reconcile P=No Print M=Manually Scheduled. |
| Runtime= | Scheduled run time (mm:ss) |
| Sweep= | 1 = element is a sweep marker |
| Transition= | Transition code (text – user-defined). This property is used as a trigger in your playout or other third party system. It is a 16 character text field, that is specific to the position (historyID) not the song. Users may make use of it to enter information of their choice. There is no predefined list of codes as this will depend upon the possibilities your system offers. Examples we have seen include X for crossfade, B for backtiming, S for start on time. |
| Type= |
Element type code: 101 = Song Element 201 = Lognote/Stopset 231 = Traffic Merge 232 = Commercial 301 = Timing Element 302 = Show Marker |
The text of the element tag is the element description.
songList
When there are songs returned, this section is included. Each unique scheduled song has a song tag. The following attributes are included for each song:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| songID= | Internal MusicMaster Song ID number |
| addDate= | Date and time this song was added to the library |
| playCount= | Number of times this song played in the returned schedule time period. |
showInstance
Additional field information about Shows in the time period can be returned. This section is included in the Reply only if there are Shows within the time period specified. The following attributes are included:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| episode= | This is the episode ID information from the Show |
| identification= | This is the identification information from the Show |
| metadataproperty= | This is a sub-property of showInstance that lists the metadata property assigned to the Show |
| showid= | |
| showInstance= |
0=New 1=Ready to Check 2=Ready to Report 3=Reported |
| showInstanceid= | |
| showName= | This is the name of the Show. This name is important when performing an update. If it does not match the existing element exactly, the Show will be replaced by a new instance of the named Show. If it matches, the existing instance will be updated. You can force it to do an update without concern for the name by omitting this attribute from your request. It is only compared if it is provided. |
showList
Additional field information about Shows in the time period can be returned. This section is included in the Reply only if there are Shows within the time period specified. The following attributes are included:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| episodeidtemplate= | This is the episode ID information from the Show |
| identification= | This is the identification information from the Show |
| metadataproperty= | This is a sub-property of showInstance that lists the metadata property assigned to the Show |
| showInstance= |
0=New 1=Ready to Check 2=Ready to Report 3=Reported |
| showid= | showid= |
| name= | This is the name of the Show. This name is important when performing an update. If it does not match the existing element exactly, the Show will be replaced by a new instance of the named Show. If it matches, the existing instance will be updated. You can force it to do an update without concern for the name by omitting this attribute from your request. It is only compared if it is provided. |
Additional field information about timing elements in the time period can be returned. The following attributes are included:
| ATTRIBUTE | DESCRIPTION |
|---|---|
|
minTime= |
Return values as MM:SS for the minimum time of the time marker |
| maxTime= | Return values as MM:SS for the maximum time of the time marker |
| resetMode= |
Returns a string of one or more letter codes depending upon which options are checked. H=Play History R=Rolling Time X=Exporting Logs |
| resetTime= | Time in MM:SS to reset the elapsed hour time to |
| timingMode= | Returns "hour," "segment" or "none" |
Additional field information about the traffic scheduled in the time period can be returned. The following attributes are included:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| startTime= | MM:SS only; included if not 0:00 |
| endTime= | MM:SS only; included if not 0:00 |
| breakCode= | Only included if not blank |
Additional field information about the commercial elements in the time period can be returned. The following attributes are included only when not blank:
| ATTRIBUTE | DESCRIPTION |
|---|---|
| spotID= | Unique traffic system ID code |
| spotTitle= | Title or description |
| spotSponsor= | Name of sponsor or advertiser |
| spotValue= | Monetary value |
| spotKey= | Used when the combination of spotID and spotTitle does not result in unique spots |
|
spotUser1= |
Additional data fields for commercials |
| spotUser2= |
Additional data fields for commercials |
| spotUser3= | Additional data fields for commercials |
One or more field tags may be included with the value of each requested field. The field tags include an id attribute with the internal field ID number and a name attribute with the user field descriptive name.
Common Usage
An initial call to retrieve the schedule will be typical, but users may have reason to change the playlist even though it has already been published to your system. That change might be the day of or into the future. The time frame is allowed is up to you. You may wish to accept changes to the next item in the playlist or an earlier time frame. The close to the real broadcast time you allow changes, the more flexibility will be provided to the music programmers. Care should be taken to only overwrite the changes so items like traffic and voice tracks are not changed.
With the initial log, you will see the songID and historyID. These should be saved so when a subsequent version of the playlist is requested you can compare the current list against the previous list. It is likely you would have also included the ID information for your system which can also be returned for comparison purposes. Changes you might see include:
- A new historyID in between two existing songIDs, along with a new songID (they do not need to be in ascending order)
- The same historyID but new song ID (song has changed)
- The historyID is removed (song and position has been deleted)
Compatibility and Version Info
Available in all versions
Attribute: transition added with MusicMaster PRO 4.0sr12
Property: estimate added with MusicMaster PRO 4.0sr23
Attribute: properties added with MusicMaster PRO 5.0sr8 (API version 5003)
mergeTraffic property details added with MusicMaster PRO 6.0sr4 (API version 5009)
showInstance details added with MusicMaster CS 3.0
showList property details added with MusicMaster CS 3.0